Connector for Event Emails

The Alemba® Email Event Connector is implemented to generate calls or requests in ASM from 3rd party event tools that send event notifications by email. Fields in the generated calls and requests are populated with data from the emails. A configuration XML file defines field mappings between the template and the contents of event emails. New calls or requests are created from emails with unique Subjects. Existing event calls or requests are updated from emails with Subjects matching previously received emails.

This section of the documentation describes the details of the connector and how to configure it to extract data from incoming emails, including:

  • The name of the .NET assembly file
  • Connection methodology
  • The requirements involved in the handling of Event Management between ASM Core and the incoming emails.

For compatibility and version support details, refer to the ASM Connector Matrix.

Use Case Scenario

Purpose

An organization receives emails from a 3rd party application to notify them of an event.

Role

The role of this connector is to pass parameters from the email into calls or requests in ASM.

Connector Description

The table below provides a description of the connector.

Information fields

Name

Connector

Emails -> ASM Core Connector

Third-party application

any supported email applications

Assembly

Alemba®.Connector.Email.dll

Configuration file

Alemba®.Connector.Email.xml
Configuration GUI Alemba®.Connector.Email.Config.exe

Connection methodology

not applicable

Connection Parameters

The connection parameters for this connector are contained within an XML file on the application server where ASM is installed. This file must be mapped to the connector Source.

Connection parameters

Description
Incoming Email Source The incoming email server source configured in System Admin, to be used by the connector.

Configuration File

The file path and name of the XML file which contains the connection details and parameters for the connector. Required.

Licensing

Contact Sales for more details.

This connector is not licensed software and can be used free of charge as part of the ASM Core license.

Installation

No install is required for this connector. Upon ASM Core install, this connector is visible in the Integration module, ready to be configured.

User Diagnostics

The connector has the facility to trace information. The data can be obtained through Polling tracing or Application tracing.

Additional Information

This connector does not include any Federated CMDB population functionality.

Connector Operation

Overview

To make the Alemba® Event Email Connector work, you must:

  1. Set up an Incoming Email Server in ASM Core
  2. Configure an Integration Source for the Email Connector
  3. Configure the XML file
  4. Create an Integration Event Mapping

 

Set up an Incoming Email Server in ASM Core

  1. Follow the steps detailed in the Email Settings topic to create an incoming email server in ASM Core that will be used by the Email Connector to retrieve emails and create calls or requests.
  2. Enter the details of the server and email account that will receive event emails from the third party application.

    3. The Call Template field in the Email Settings is ignored by the connector, which instead uses the Using template field in the Event Type Mapping Details window.

  3. In the settings for the incoming email server in ASM Core, the Active checkbox must be unselected.

    4. Conflicts will occur if the mail server is not set to be inactive in the Email Settings.

  4. Continue completing the settings for the incoming email server in ASM Core, as instructed in the Email Settings topic.
  5. Select to save the changes.

Configure an Integration Source for the Email Connector

  1. Select and then Admin. From the submenu, select Integration.
  1. Select the Sources option from the explorer pane.
  2. Select the button on the toolbar. In the pop up window, select Alemba® Email Event Connector from the drop-down list.
  3. In the Integration Source Details window, complete the details.
    4. Name Type a name for the integration source. Required.
    Status This field is pre-filled with the Active status.
    Connector This field is pre-filled with the Connector type.
    Assembly.TypeName This field is pre-filled based on the selected connector as defined in the Connector DLL. Read-only.
    Incoming Email Source

    Use the drop down to select the Incoming Email Server, configured in Email Settings in System Admin, that will receive the event emails. The connector will regularly check the inbox of that mail account.

    The account configured in Email Settings must be set to Inactive.

    Configuration File

    The file path and name of the XML file which contains the field mappings for the connector. Required.
  4. Select to save the changes.

Configure the XML file

An executable has been provided to assist in the configuration of the Alemba®.Connector.Email.xml file, where the field mappings are defined.

  1. Run the configuration GUI
    • Log onto the ASM web server, if you're not already logged on
    • Navigate to the ASM root folder and run Alemba®.Connector.Email.Config.exe

      • C:\Program Files\Alemba\ASM\Alemba®.Connector.Email.Config.exe

    • The ASM Email Event Connector Config window opens

      • On first-time configuration, the GUI opens with a simple email example to demonstrate how the configuration tool works. The XML file is pre-configured with field mappings for the example email. To see the example field mappings, select Open and select the file Alemba®.Connector.Email.xml.

  2. Configure the settings:
System Select the system configured with the Email Connector Source. The default system is selected by default.
Incoming Email Select the incoming mail account configured in the Email Settings window in System Admin, that will receive the event emails.

The selected mail account must be set to Inactive in the Email Settings.
After selecting the System and Incoming Email, select

select to display the contents of the first email in the inbox.

From The from address of the event email
Subject The subject of the event email
Body The body of the event email
Headers The email header information contained in the event email

If no email contents are displayed, the settings may be incorrect, or there is no email in the inbox.

Save the configured System and Incoming Email settings.
Configs

Use the Configs table to create fields for each unit of data you want imported into ASM from the emails. Fields created here appear as selectable Event Fields in the Incoming tab of the Event Type Mappings Details screen. Create a row for each field to be mapped to a field in a ASM call or request, configuring the columns as follows:

Field The name of the field to display in the Event Fields column in the Incoming tab of the Event Type Mappings Details screen in ASM.
Type Select the type of field from the list.
Source Select the source from the list.
Header Enter the Name of the record in the Headers section to extract data from, if applicable.
Expression

Define a formula, based on Regular Expression parsing, to extract the required parameters from the event email.

The email contains UserID: 123

Therefore the expression would be defined as UserID: (?<value>.+)

And the extracted value is 123
Date Format

Enter a format if DateTime was selected as the Type. If blank, will default to the server format. Leave this field blank if Date/Time was not selected as the Type.

dd/MM/yyyy

Default Enter a value to use as default if none can be extracted from the email.
Test This column displays the value that will be extracted from the email using the configured settings. To run the test, select .

select to test the field mapping configuration. The outcome for each configured field (row) appears in the Test column.
  1. select Save to save the field mapping settings to the XML file.

    2. Ensure you have the correct account permissions required to modify the XML file.

Create an Integration Event Mapping

Before you start

If the Event Management checkbox in the Integration Platform administration screen is selected, the Event Management functionality starts running as soon as a proper Event Mapping is saved. When starting, the connector checks the configured database table and logs a call or request for every item that is present and fulfills the criteria that are implemented in the Event mapping. This could lead to a large number of calls/requests being created when activating the Event Management functionality.

One solution to avoid this behavior is to include in the Event criteria setting an item based on a date attribute. For example, you could plan to “go live” with Event management on a precise date and, as a consequence, specify that the value of date field in the external table has to be after this date before any action can be triggered in ASM Core.

  1. Follow the steps detailed in the Managing Event Type Mappings topic, up to the section that describes the Actions tab.
  2. In the Actions tab, it is recommended to select Update as the action for "When Deleted externally". For more information refer below - Configuring the Actions Tab.
  1. After the Actions tab is configured, continue completing the settings for the Event Mapping as instructed in the Managing Event Type Mappings topic.
  2. Select to save the changes.

Configuring the Actions Tab

Settings defined in the Actions tab of the Event Type Mappings will have a significant impact on calls and requests created by the connector.

New calls or requests are created when the connector finds an email with a unique Subject.

Existing calls or requests created from event emails, are updated when the connector finds an email with a Subject that was previously processed.

When Updated externally

This transaction is used when an email is received that has the same subject as a previous email that already generated a call or request through the connector. The action that is selected from the dropdown list determines what happens to the existing call or request.

Close This action has no effect on the existing call or request.
Update Updates the existing call or request, updating mapped field values (if needed) and writes an 'update' entry into the call or request history.
Add Note Adds a note to the existing call or request's history. Mapped fields are not updated.
Take no action This action has no effect on the existing call or request.
When Updated externally and Call or Request is closed

This transaction is used when an email is received that has the same subject as a previous email that already generated a call or request through the connector, and that call or request is closed. The action that is selected from the dropdown list determines what happens to the existing call or request.

Re-open Reopens the closed call or request, updates mapped field values (if needed) and writes an 'update' entry into the call or request history.
Log new and link existing Logs a new call or request and links it to the closed call.
Add Note Adds a note to the closed call or request's history. Mapped fields are not updated.
Take no action This action has no effect on the existing call or request.
When Notified externally This transaction is not used by this connector and can be ignored.
When Notified externally and Call or Request is closed This transaction is not used by this connector and can be ignored.
When Resolved externally This transaction is not used by this connector and can be ignored.
When Resolved externally and Call or Request is closed This transaction is not used by this connector and can be ignored.
When Deleted externally

This transaction is used when a new email is found in the inbox, and a call or request is generated by the connector for the event. The action that is selected from the dropdown list determines what happens to the call or request at the time it is created.

Close Logs the call or request and then immediately closes it
Update Logs the call or request and then adds a note to the history
Add Note Logs the call or request and then adds a note to the history
Take no action No call or request is logged
When Deleted externally and Call or Request is closed This transaction is not used by this connector and can be ignored.